// Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

part of dart.core;

// TODO: Convert this abstract class into a concrete class double
// that uses the patch class functionality to account for the
// different platform implementations.

/**
 * 双精度浮点数。
 *
 * 在Dart中，double包含编译常量，运算操作，以及继承自[num]、特殊化的运算操作。
 * double是符合IEEE 754标准的64位浮点数。
 *
 * [double]有传染性。对[double]进行操作，返回结果也是[double]。
 *
 * 在试图继承或实现double类的时候，会产生一个编译时错误。
 */
abstract class double extends num {
  static const double NAN = 0.0 / 0.0;
  static const double INFINITY = 1.0 / 0.0;
  static const double NEGATIVE_INFINITY = -INFINITY;
  static const double MIN_POSITIVE = 5e-324;
  static const double MAX_FINITE = 1.7976931348623157e+308;

  double remainder(num other);

  /** 加法运算符。 */
  double operator +(num other);

  /** 减法运算符。 */
  double operator -(num other);

  /** 乘法运算符。 */
  double operator *(num other);

  double operator %(num other);

  /** 除法运算符。 */
  double operator /(num other);

  /**
   * 截断除法运算符，通常称为取整。
   *
   * `a ~/ b`取整的结果等同于
   * `(a / b).truncate()`。
   */
  int operator ~/(num other);

  /** 负值运算符。 */
  double operator -();

  /** 返回[double]的绝对值。 */
  double abs();

  /**
   * 返回double的数值符号。
   *
   * 如果值小于0，返回-1.0；如果值大于0，返回1.0；如果是-0.0，0.0或NaN，则返回值本身。
   */
  double get sign;

  /**
   * 四舍五入，返回最接近`this`的整数。
   *
   * 如果没有最接近的整数，则返回距离0较远的那个整数：
   *  `(3.5).round() == 4` 和 `(-3.5).round() == -4`。
   *
   * 如果`this`不是有限值，如`NaN`或`INFINITY `，会抛出[UnsupportedError]。
   */
  int round();

  /**
   * 向下取整，或者说向下舍入，返回不大于`this`的最大整数。
   *
   * 如果`this`不是有限值，如`NaN`或`INFINITY `，会抛出[UnsupportedError]。
   */
  int floor();

  /**
   * 向上取整，或者说向上舍入，返回不小于`this`的最小整数。
   *
   * 如果`this`不是有限值，如`NaN`或`INFINITY `，会抛出[UnsupportedError]。
   */
  int ceil();

  /**
   * 截断，通常称为取整。丢弃`this`的任何小数部分，返回整数。
   *
   * 如果`this`不是有限值，如`NaN`或`INFINITY `，会抛出[UnsupportedError]。
   */
  int truncate();

  /**
   * 四舍五入，以double值返回最接近`this`的整数。
   *
   * 如果没有最接近的整数，则返回距离0较远的那个整数：
   *  `(3.5).roundToDouble() == 4` 和 `(-3.5).roundToDouble() == -4`。
   *
   * 如果`this`已经是整数的double形式，包括`-0.0`，或不是一个有限值，
   * 则返回值本身，不做任何修改。
   *
   * 对于舍入，`-0.0`被认为比`0.0`小。因此，`-0.0`被认为比`0.0`更靠近负数。
   * 这就意味着，对于`-0.5 < d < 0.0`范围内的数值`d`，返回结果是`-0.0`。
   */
  double roundToDouble();

  /**
   * 向下取整，或者说向下舍入，以double值返回不大于`this`的最大整数。
   *
   * 如果`this`已经是整数的double形式，包括`-0.0`，或不是一个有限值，
   * 则返回值本身，不做任何修改。
   *
   * 对于舍入，`-0.0`被认为比`0.0`小。
   * 因此，对于`0.0 < d < 1.0`范围内的数值`d`，返回结果是`0.0`。
   */
  double floorToDouble();

  /**
   * 向上取整，或者说向上舍入，以double值返回不小于`this`的最小整数。
   *
   * 如果`this`已经是整数的double形式，包括`-0.0`，或不是一个有限值，
   * 则返回值本身，不做任何修改。
   *
   * 对于舍入，`-0.0`被认为比`0.0`小。
   * 因此，对于`-1.0 < d < 0.0`范围内的数值`d`，返回结果是`-0.0`。
   */
  double ceilToDouble();

  /**
   * 截断，通常称为取整。丢弃`this`的任何小数部分，以double值返回整数。
   *
   * 如果`this`已经是整数的double形式，包括`-0.0`，或不是一个有限值，
   * 则返回值本身，不做任何修改。
   *
   * 对于舍入，`-0.0`被认为比`0.0`小。
   * 因此，对于数值`d`，如果取值范围是`-1.0 < d < 0.0`，返回结果是`-0.0`；
   * 如果取值范围是`0.0 < d < 1.0`，返回结果是`0.0`。
   */
  double truncateToDouble();

  /**
   * 返回一个用来表示该[double]数值的字符串。
   *
   * 表现为原义的数值，使字符串最接近[double]值。
   *
   * * 返回 "NaN"，是Not-a-Number的简写，表示“不明确的数值”
   * * 返回 "Infinity" 或 "-Infinity"，如果值为正无穷大或负无穷大
   * * 返回 "-0.0"，如果值为负零
   *
   * 对于所有的double，`d`，转换为字符串后再解析回double，值不变：
   * `d == double.parse(d.toString())` （除非`d`是NaN）。
   */
  String toString();

  /**
   * 将[source]作为double的原义字符串进行解析，返回解析后的值。
   *
   * 接受一个可选的符号（`+`或`-`），然后要么是字符串"Infinity"，要么是字符串"NaN"，
   * 或者一个浮点数。浮点数由尾数和指数（可选）组成。尾数要么是小数点`.`跟一个数列，
   * 要么是数列跟小数点和数字。指数部分包括字符"e"或"E"，一个可选的符号，然后是一个或多个数字。
   *
   * 两端的空格会被忽略。
   *
   * 如果[source]不是一个有效的double原义字符串，
   * 回调函数[onError]将以[source]为参数被触发，函数的返回值将作为解析的值被返回。
   * 如果没有设置`onError`，则会抛出异常[FormatException]。
   *
   * 回调函数[onError]仅在[source]是一个无效的格式化[String]时被调用。
   * 如果[source]因为其他原因无效，将不会触发，例如`null`。
   *
   * 接受的字符串例子：
   *
   *     "3.14"
   *     "  3.14 \xA0"
   *     "0."
   *     ".0"
   *     "-1.e3"
   *     "1234E+7"
   *     "+.12e-9"
   *     "-NaN"
   */
  external static double parse(String source,
                               [double onError(String source)]);
}
